---
title: 'Quickstart with Docker'
description: 'Get up and running with Droidrun in Docker quickly and effectively'
---

This guide will help you get Droidrun running in a Docker container, controlling your Android device through natural language without installing it natively.

### Host configuration

Follow the steps below to ensure your host system is properly configured to mount the smartphone inside the container.

1. Make sure you’ve completed the prerequisite steps in the [Quickstart](/quickstart). Then verify the ADB connection with `adb devices`. This should list your phone as “device” along with its Serial Number. If the phone appears as `unauthorized` make sure to accept the prompt on your phone.

2. Confirm that the ADB keys have been correctly created. Check for an `.android` folder under your `$HOME` directory that contains: `adb.5037`, `adbkey`, and `adbkey.pub`.

3. Set up a custom rule to uniquely identify your phone and map it to a static path:
   - Open a terminal and find your device’s `idVendor` and `idProduct` using the `lsusb` command.

      In the example below, the `idVendor` and `idProduct` are `18d1` and `4ee2`, respectively.

      ```bash
      > lsusb
      Bus 003 Device 002: ID 18d1:4ee2 Google Inc. Nexus/Pixel Device (MTP + debug)
      ```

   - Create a new file (sudo may be required) under `/etc/udev/rules.d` and name it `51-android.rules`.

   - Add the following content and save the file:

      ```bash
      SUBSYSTEM=="usb", ATTR{idVendor}=="XXXX", ATTR{idProduct}=="YYYY", ATTR{serial}=="SSSS", MODE="0666", GROUP="plugdev", SYMLINK+="phone1/phone"
      ```

      where `XXXX`, `YYYY`, and `SSSS` are the vendor ID, product ID, and serial number of your phone.

      This static mapping is required because otherwise the phone’s mount path will change across reconnections!

   - Reload the rules

      ```bash
      sudo udevadm control --reload-rules
      sudo udevadm trigger
      ```

4. Kill the ADB server on the host so that the container can actually detect the phone:

   ```bash
   adb kill-server
   ```

### Usage

Pull the image from the GitHub Container Registry:

```bash
docker pull ghcr.io/droidrun/droidrun:latest
```

Before running the container, note that the following options are always required when launching Droidrun in Docker:

| Docker option | What it does | Why it matters for Droidrun |
|---------------|--------------|-----------------------------|
| `--group-add plugdev` | Adds the host user to the container’s `plugdev` group. | Gives the container permission to access USB devices (e.g., your Android phone) without requiring root. |
| `--device /dev/phone1/phone:/dev/phone` | Maps a specific USB device file from the host into the container. Thanks to our udev rule, the phone will always be mapped here. | Allows Droidrun to see the phone as `/dev/phone` inside the container, so it can communicate with the device. |
| `--volume /dev/bus/usb:/dev/bus/usb` | Mounts the entire USB bus directory. | Provides access to all connected USB devices, enabling Droidrun to discover and interact with the phone. |
| `--volume ~/.android:/home/droidrun/.android` | Mounts the host’s Android configuration directory into the container. | Stores ADB keys and settings so that once you grant permission on the host, Droidrun doesn’t prompt for it again inside the container. |

The Docker image uses the `droidrun` entrypoint, which means you can use any of the CLI commands described in the [CLI Usage](/guides/cli) section and append it to the following base command:

```bash
docker run \
  --group-add plugdev \
  --device /dev/phone1/phone:/dev/phone \
  --volume /dev/bus/usb:/dev/bus/usb \
  --volume ~/.android:/home/droidrun/.android \
  ghcr.io/droidrun/droidrun:latest \
  <droidrun command>
```

#### Setup the Portal APK

Simply run the container with the `setup` CLI command.

```bash
docker run \
  --group-add plugdev \
  --device /dev/phone1/phone:/dev/phone \
  --volume /dev/bus/usb:/dev/bus/usb \
  --volume ~/.android:/home/droidrun/.android \
  ghcr.io/droidrun/droidrun:latest \
  setup
```

#### Verify the setup

Simply run the container with the `ping` CLI command.

```bash
docker run \
  --group-add plugdev \
  --device /dev/phone1/phone:/dev/phone \
  --volume /dev/bus/usb:/dev/bus/usb \
  --volume ~/.android:/home/droidrun/.android \
  ghcr.io/droidrun/droidrun:latest \
  ping
```

#### Run some agents

Now you’re ready to control your device using Docker and natural language:

```bash
# Using default configuration with Google API key
docker run --group-add plugdev --device /dev/phone1/phone:/dev/phone --volume /dev/bus/usb:/dev/bus/usb --volume ~/.android:/home/droidrun/.android --env GOOGLE_API_KEY=your-api-key-here ghcr.io/droidrun/droidrun:latest run "Open the settings app and tell me the Android version"

# Override provider and model
docker run --group-add plugdev --device /dev/phone1/phone:/dev/phone --volume /dev/bus/usb:/dev/bus/usb --volume ~/.android:/home/droidrun/.android --env OPENAI_API_KEY=your-api-key-here ghcr.io/droidrun/droidrun:latest run "Open a browser and search for droidrun" -p OpenAI -m gpt-40

# Use a locally-running LLM, example for LM Studio running in the LAN
docker run --group-add plugdev --device /dev/phone1/phone:/dev/phone --volume /dev/bus/usb:/dev/bus/usb --volume ~/.android:/home/droidrun/.android --network host ghcr.io/droidrun/droidrun:latest run "Open a browser and search for droidrun" -p OpenAILike -m gpt-oss --api_base http://IP-of-LMStudio-server:PORT/v1
```

#### Troubleshooting

* Error response from daemon

   If you enconter the following error:

   ```
   docker: Error response from daemon: error gathering device information while adding custom '/dev/phone1/phone': no such file or directory
   ```

   it usually indicates one of two things:
   - The phone isn’t mounted at the expected custom path. Verify that `/dev/phone1/phone` exists.
   - An ADB server is still running on the host. Stop it with `adb kill-server`.

---

## Next Steps

- [CLI Usage](/guides/cli) - Dive into the various parameters and start building your own projects with the docker!
